GCP Terraform Module Reference

The nOps GCP Integration Terraform Module automates the GCP-side configuration — all IAM role grants and API enablement — in a single terraform apply.

Before Using Terraform

You must complete these manual steps first:

1. Prerequisites — Configure billing exports in GCP
2. Link GCP Billing Data to nOps — Create the integration in nOps to get the service account email

The Terraform module handles Step 2 (Grant Permissions) and Step 3 (Enable APIs) from the integration guide.

---

GitHub Repository

Repository: github.com/nops-io/terraform-gcp-nops-integration

---

What the Module Does

With a single module invocation, you can configure:

Category	What Gets Configured
Organization IAM	Cloud Asset Viewer, Browser, Recommender Viewer, Logs Viewer, Compute Viewer, Container Viewer, Cloud SQL Viewer, Cloud Run Viewer
Billing Account IAM	Billing Account Viewer
Project IAM	Service Usage Consumer
Dataset IAM	BigQuery Data Viewer (on all 3 billing export datasets)
APIs	Cloud Asset, Cloud Billing, Recommender (+ optional BigQuery Reservation)

---

Quick Start

1. Create Configuration

Create a main.tf file:

terraform {
  required_version = ">= 1.0"
  
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.0"
    }
  }
}

provider "google" {
  # Uses Application Default Credentials
  # Run: gcloud auth application-default login
}

module "nops_gcp_integration" {
  source = "github.com/nops-io/terraform-gcp-nops-integration"
  
  # Required: Your GCP identifiers
  organization_id           = "123456789012"
  billing_account_id        = "XXXXXX-XXXXXX-XXXXXX"
  billing_export_project_id = "your-billing-export-project"
  
  # Required: nOps service account email (from nOps integration setup)
  nops_service_account_email = "your-nops-sa@project.iam.gserviceaccount.com"
  
  # Required: BigQuery dataset IDs for billing exports
  bigquery_detailed_usage_cost_dataset_id     = "project-id:dataset_name"
  bigquery_pricing_dataset_id                 = "project-id:dataset_name"
  bigquery_committed_use_discounts_dataset_id = "project-id:dataset_name"
}

2. Apply

# Authenticate
gcloud auth application-default login

# Initialize and apply
terraform init
terraform plan
terraform apply

---

Input Variables

Variable	Description	Required
organization_id	GCP Organization ID	Yes
billing_account_id	GCP Billing Account ID	Yes
billing_export_project_id	Project ID where billing exports are configured (where APIs are enabled)	Yes
nops_service_account_email	nOps service account email	Yes
bigquery_detailed_usage_cost_dataset_id	Dataset ID for Detailed Usage Cost export	Yes
bigquery_pricing_dataset_id	Dataset ID for Pricing export	Yes
bigquery_committed_use_discounts_dataset_id	Dataset ID for CUD export	Yes
enable_bigquery_reservation_api	Enable BigQuery Reservation API (for flat-rate pricing)	No (default: false)
grant_nops_iam_roles	Grant organization-level IAM roles	No (default: true)
grant_nops_billing_iam_roles	Grant billing account IAM roles	No (default: true)
grant_nops_project_iam_roles	Grant project-level IAM roles	No (default: true)
grant_nops_bigquery_dataset_iam_roles	Grant BigQuery dataset IAM roles	No (default: true)
enable_domain_restricted_sharing	Configure domain restricted sharing to nOps	no
nops_customer_id	The nOps Google Workspace Customer ID	no

---

Finding Your IDs

Organization ID

gcloud organizations list

Use the ID column value.

Billing Account ID

gcloud billing accounts list

Use the ACCOUNT_ID column (format: XXXXXX-XXXXXX-XXXXXX).

Billing Export Project ID

# List all projects
gcloud projects list

# Or get current project ID
gcloud config get-value project

Use the PROJECT_ID column (not the project name). This is the project where your billing exports are configured and where APIs will be enabled.

BigQuery Dataset IDs

# List datasets in your billing export project
gcloud bigquery datasets list --project=YOUR_PROJECT_ID

Or find them in Billing → Billing Export in the GCP Console.

Format: project-id:dataset_name (e.g., my-project:gcp_billing_export)

---

Authentication

Application Default Credentials

Recommended for local development:

gcloud auth application-default login

Service Account Key

provider "google" {
  credentials = file("path/to/service-account-key.json")
}

Or use environment variable:

export GOOGLE_APPLICATION_CREDENTIALS="path/to/key.json"

Workload Identity

For CI/CD pipelines running in GCP:

provider "google" {
  # Credentials automatically detected
}

---

Required Permissions

The user or service account running Terraform needs:

Level	Permissions
Organization	resourcemanager.organizations.get, resourcemanager.projects.list, resourcemanager.organizationIamPolicies.set
Billing Account	billing.accounts.getIamPolicy, billing.accounts.setIamPolicy
Project	serviceusage.services.enable, resourcemanager.projects.setIamPolicy
BigQuery	bigquery.datasets.setIamPolicy

These can be granted via roles like roles/owner, roles/resourcemanager.organizationAdmin, or roles/billing.admin.

---

Troubleshooting

Error	Solution
Permission denied	Verify your credentials have the required permissions listed above
Project not found	Check that organization_id and billing_account_id are correct
APIs not enabling	Ensure billing is enabled on the project; wait a few minutes for propagation
Domain restricted sharing error	Add the nOps Customer ID to your organization's allowed domains (see Prerequisites)

---

OpenTofu Compatibility

This module works with both Terraform and OpenTofu. Simply replace terraform with tofu:

tofu init
tofu plan
tofu apply